---
layout: docs
page_title: Use Vault Agent as an API proxy
description: >-
  Use auto-authentication and configure Vault Agent as a proxy for the Vault API.
---

# Use Vault Agent as an API proxy

@include 'alerts/deprecated.mdx'

Vault Agent's API proxy functionality allows you to use Vault Agent's API as a proxy
for Vault's API.

<Warning title="Use Vault Proxy">

  [Static secret caching](/vault/docs/agent-and-proxy/proxy/caching/static-secret-caching)
  (KVv1 and KVv2) with API proxy minimizes the number of requests forwarded to
  Vault. Vault Agent does not support static secret caching with API proxy. We
  recommend using [Vault Proxy](/vault/docs/agent-and-proxy/proxy) for API proxy
  workflows.

</Warning>

## Functionality

The [`listener` stanza](/vault/docs/agent-and-proxy/agent#listener-stanza) for Vault Agent configures a listener for Vault Agent. If
its `role` is not set to `metrics_only`, it will act as a proxy for the Vault server that
has been configured in the [`vault` stanza](/vault/docs/agent-and-proxy/agent#vault-stanza) of Vault Agent. This enables access to the Vault
API from the Agent API, and can be configured to optionally allow or force the automatic use of
the auto-auth token for these requests, as described below.

If a `listener` has been configured alongside a `cache` stanza, the API proxy will
first attempt to utilize the cache subsystem for qualifying requests, before forwarding the
request to Vault. See the [caching docs](/vault/docs/agent-and-proxy/agent/caching) for more information on caching.

## Using auto-auth token

Vault Agent allows for easy authentication to Vault in a wide variety of
environments using [auto-auth](/vault/docs/agent-and-proxy/autoauth). By setting the
`use_auto_auth_token` (see below) configuration, clients will not be required
to provide a Vault token to the requests made to the Agent. When this
configuration is set, if the request doesn't already bear a token, then the
auto-auth token will be used to forward the request to the Vault server. This
configuration will be overridden if the request already has a token attached,
in which case, the token present in the request will be used to forward the
request to the Vault server.

## Forcing auto-auth token

Vault Agent can be configured to force the use of the auto-auth token by using
the value `force` for the `use_auto_auth_token` option. This configuration
overrides the default behavior described above in [Using auto-auth
token](/vault/docs/agent-and-proxy/agent/apiproxy#using-auto-auth-token), and instead ignores any
existing Vault token in the request and instead uses the auto-auth token.


## Configuration (`api_proxy`)

The top level `api_proxy` block has the following configuration entries:

- `use_auto_auth_token` `(bool/string: false)` - If set, the requests made to Agent
without a Vault token will be forwarded to the Vault server with the
auto-auth token attached. If the requests already bear a token, this
configuration will be overridden and the token in the request will be used to
forward the request to the Vault server. If set to `"force"` Agent will use the
auto-auth token, overwriting the attached Vault token if set.

The following two `api_proxy` options are only useful when making requests to a Vault
Enterprise cluster, and are documented as part of its
[Eventual Consistency](/vault/docs/enterprise/consistency#vault-proxy-and-consistency-headers)
page.

- `enforce_consistency` `(string: "never")` - Set to one of `"always"`
or `"never"`.

- `when_inconsistent` `(string: optional)` - Set to one of `"fail"`, `"retry"`,
or `"forward"`.

### Example configuration

Here is an example of a `listener` configuration alongside `api_proxy` configuration to force the use of the auto_auth token
and enforce consistency.

```hcl
# Other Vault agent configuration blocks
# ...

api_proxy {
  use_auto_auth_token = "force"
  enforce_consistency = "always"
}

listener "tcp" {
    address = "127.0.0.1:8100"
    tls_disable = true
}
```
